package com.bzkj.basicinfo.service.putaway;

import com.bzkj.basicinfo.domain.putaway.WmsPutawayTaskEntity;
import com.bzkj.common.core.domain.AjaxResult;
import com.bzkj.common.core.page.TableDataInfo;
import java.math.BigDecimal;

/**
 * 上架管理服务接口
 *
 *@author lixinyu
 * @date 2025-10-22
 */
public interface WmsPutawayTaskService {

    /**
     * 查询上架任务列表（分页）
     */
    TableDataInfo getPutawayTaskList(WmsPutawayTaskEntity entity, int pageNum, int pageSize);

    /**
     * 根据ID查询上架任务详情（含明细）
     */
    AjaxResult getPutawayTaskDetail(Long id);

    /**
     * 创建上架任务（根据收货单明细）
     */
    AjaxResult createPutawayTask(Long receiveDetailId, String operator);

    /**
     * 批量创建上架任务（根据收货单）
     */
    AjaxResult batchCreatePutawayTask(Long receiveOrderId, String operator);

    /**
     * 分配上架任务
     */
    AjaxResult assignTask(Long id, String assignedTo, String operator);

    /**
     * PDA上架确认
     */
    AjaxResult confirmPutaway(Long taskId, BigDecimal putawayQuantity,
                             String locationCode, String operator);

    /**
     * 完成上架任务
     */
    AjaxResult completeTask(Long id, String operator);

    /**
     * 删除上架任务
     */
    AjaxResult deletePutawayTask(Long id, String operator);

    /**
     * 上架异常处理（新增方法）
     * 将收货单状态回滚至「4 - 异常」，记录异常原因、人员、时间
     * @param taskId 上架任务ID
     * @param exceptionReason 异常原因
     * @param exceptionDesc 异常描述
     * @param photoUrls 相关照片
     * @param operator 操作人
     * @return 操作结果
     */
    AjaxResult handlePutawayException(Long taskId, String exceptionReason,
                                    String exceptionDesc, String photoUrls, String operator);

    /**
     * 重置上架任务状态（新增方法）
     * 将异常状态的上架任务重新设置为待上架状态
     * @param taskId 上架任务ID
     * @param operator 操作人
     * @return 操作结果
     */
    AjaxResult resetPutawayTaskStatus(Long taskId, String operator);

    /**
     * 强制完成上架任务（新增方法）
     * 用于处理特殊情况下的上架任务强制完成
     * @param taskId 上架任务ID
     * @param reason 强制完成原因
     * @param operator 操作人
     * @return 操作结果
     */
    AjaxResult forceCompletePutaway(Long taskId, String reason, String operator);
}
